<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>reStructuredText 简明教程</title>
<style type="text/css">

/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Date: $Date$
:Revision: $Revision$
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin-left: 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left {
  clear: left }

img.align-right {
  clear: right }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font-family: serif ;
  font-size: 100% }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em ;
  background-color: #eeeeee }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

tt.docutils {
  background-color: #eeeeee }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="rst">
<h1 class="title"><em>re</em><strong>Structured</strong><sup>Text</sup> 简明教程</h1>
<p>060724  17:58</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">作者:</th><td class="field-body">Laurence</td>
</tr>
<tr class="field"><th class="field-name">邮箱:</th><td class="field-body"><a class="reference" href="mailto:2999am&#64;gmail.com">2999am&#64;gmail.com</a></td>
</tr>
<tr class="field"><th class="field-name">ID:</th><td class="field-body">Kardinal &#64; Ubuntu.org.cn论坛</td>
</tr>
<tr class="field"><th class="field-name">版权:</th><td class="field-body">This document has been placed in the public domain</td>
</tr>
<tr class="field"><th class="field-name">参考:</th><td class="field-body">《结构化文本入门(Karron Qiu)》 《Quick <em>re</em><strong>Structured</strong><sup>Text</sup>》 《Vim <em>re</em><strong>Structured</strong><sup>Text</sup>》 《<em>re</em><strong>Structured</strong><sup>Text</sup> Interpreted Text Roles》</td>
</tr>
</tbody>
</table>
<div class="contents topic">
<p class="topic-title first"><a id="id1" name="id1">索引</a></p>
<ul class="simple">
<li><a class="reference" href="#wytiwyg-wysiwyg" id="id52" name="id52">WYTIWYG &amp; WYSIWYG</a><ul>
<li><a class="reference" href="#id2" id="id53" name="id53">所见即所得</a></li>
<li><a class="reference" href="#id3" id="id54" name="id54">所想即所得</a></li>
</ul>
</li>
<li><a class="reference" href="#id4" id="id55" name="id55"><em>re</em><strong>Structured</strong><sup>Text</sup></a></li>
<li><a class="reference" href="#id5" id="id56" name="id56">基本元素</a><ul>
<li><a class="reference" href="#id6" id="id57" name="id57"><strong>字串元素</strong></a></li>
<li><a class="reference" href="#id7" id="id58" name="id58"><strong>行元素</strong></a></li>
<li><a class="reference" href="#id8" id="id59" name="id59"><strong>块元素</strong></a></li>
</ul>
</li>
<li><a class="reference" href="#id9" id="id60" name="id60">特殊元素</a><ul>
<li><a class="reference" href="#id10" id="id61" name="id61">页面元素</a></li>
<li><a class="reference" href="#id11" id="id62" name="id62">行块元素</a></li>
<li><a class="reference" href="#id12" id="id63" name="id63">超级块元素</a></li>
<li><a class="reference" href="#id13" id="id64" name="id64">物件元素</a></li>
<li><a class="reference" href="#id14" id="id65" name="id65">自定义元素</a></li>
</ul>
</li>
<li><a class="reference" href="#id15" id="id66" name="id66">对象</a><ul>
<li><a class="reference" href="#id16" id="id67" name="id67">标题</a></li>
<li><a class="reference" href="#id17" id="id68" name="id68">行内</a></li>
<li><a class="reference" href="#id26" id="id69" name="id69">脱字符</a></li>
<li><a class="reference" href="#id27" id="id70" name="id70">链接</a></li>
<li><a class="reference" href="#id29" id="id71" name="id71">物件别名</a></li>
<li><a class="reference" href="#id30" id="id72" name="id72">列表</a></li>
<li><a class="reference" href="#id31" id="id73" name="id73">表格</a></li>
<li><a class="reference" href="#id32" id="id74" name="id74">脚注</a></li>
<li><a class="reference" href="#id33" id="id75" name="id75">提示符引用</a></li>
<li><a class="reference" href="#id34" id="id76" name="id76">预定义</a></li>
</ul>
</li>
<li><a class="reference" href="#id35" id="id77" name="id77">项目管理</a></li>
<li><a class="reference" href="#restructuredtext" id="id78" name="id78">搭建reStructuredText环境</a><ul>
<li><a class="reference" href="#linux" id="id79" name="id79">Linux</a></li>
<li><a class="reference" href="#windows" id="id80" name="id80">Windows</a></li>
</ul>
</li>
<li><a class="reference" href="#id36" id="id81" name="id81">reStructuredText命令</a></li>
<li><a class="reference" href="#id37" id="id82" name="id82">定制</a></li>
<li><a class="reference" href="#id38" id="id83" name="id83">代码风格</a><ul>
<li><a class="reference" href="#id39" id="id84" name="id84">缩进</a></li>
<li><a class="reference" href="#id40" id="id85" name="id85">空行</a></li>
<li><a class="reference" href="#id41" id="id86" name="id86">下划线</a></li>
<li><a class="reference" href="#id42" id="id87" name="id87">标题</a></li>
<li><a class="reference" href="#id43" id="id88" name="id88">标题链接</a></li>
<li><a class="reference" href="#id44" id="id89" name="id89">表格</a></li>
<li><a class="reference" href="#id45" id="id90" name="id90">别名</a></li>
<li><a class="reference" href="#id46" id="id91" name="id91">链接</a></li>
<li><a class="reference" href="#id47" id="id92" name="id92">列表</a></li>
</ul>
</li>
<li><a class="reference" href="#id48" id="id93" name="id93">编辑器设定</a><ul>
<li><a class="reference" href="#vim" id="id94" name="id94">Vim</a></li>
<li><a class="reference" href="#emacs" id="id95" name="id95">Emacs</a></li>
</ul>
</li>
<li><a class="reference" href="#faq" id="id96" name="id96">FAQ</a><ul>
<li><a class="reference" href="#id49" id="id97" name="id97">空行</a></li>
<li><a class="reference" href="#id50" id="id98" name="id98">消除空格</a></li>
<li><a class="reference" href="#id51" id="id99" name="id99">缩进和空格</a></li>
</ul>
</li>
</ul>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id52" id="wytiwyg-wysiwyg" name="wytiwyg-wysiwyg">WYTIWYG &amp; WYSIWYG</a></h1>
<div class="section">
<h2><a class="toc-backref" href="#id53" id="id2" name="id2">所见即所得</a></h2>
<p>WYSIWYG ( What You See Is What You Get )</p>
<blockquote>
这个概念非常流行。就是说制作过程中所见到的，和最终所得到的结果一致。</blockquote>
<div class="line-block">
<div class="line"><br /></div>
</div>
<blockquote>
<p>比如我用DW编辑一个网页文件，在编辑的过程中，我可以设定内容的格式、排版、色彩等属性，
而最终得到的网页，完全符合了我的愿望。</p>
<p>我们都知道，网页文件使用的是 <strong>Html</strong> 标记语言。
比如加粗某处文字，我们要使用标签 <tt class="docutils literal"><span class="pre">&lt;b&gt;</span></tt> ，然后是我们要加粗的文字，比如 <strong>粗体</strong>
最后再使用标签 <tt class="docutils literal"><span class="pre">&lt;/b&gt;</span></tt> 来结束它，不然的话， <strong>粗体</strong> 后面的文字也要被加粗了……
因为 Html 解析器 （一般来说，就是浏览器）没法子判断到底在哪儿结束“加粗”这一行为。
源文件大致是这样的：</p>
<pre class="literal-block">
&lt;b&gt;粗体&lt;/b&gt;
</pre>
<p>一个完整的Html文件就是由许许多多这样的标签构成的。标签和标签之间可以嵌套。比如：</p>
<pre class="literal-block">
&lt;html&gt;
&lt;head&gt;头部&lt;/head&gt;
&lt;body&gt;
&lt;p&gt;    正文                                               &lt;/p&gt;
&lt;p&gt;    这里是段落2                                          &lt;/p&gt;
&lt;p&gt;    这里是&lt;b&gt;粗体&lt;/b&gt;，这里是&lt;font color=red&gt;红色字体&lt;/font&gt;&lt;/p&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>
<p>当然了，大多数时候，Html的源文件比较复杂，远远没有这么简单。
可不要被它可怕的外表吓坏了，一个Html文件，无论多么复杂，它总是具有这种结构，
只要您熟悉了足够多的标签，Html对于您来说，完全是纸老虎：）</p>
<p>必须承认的是，如果没有所见即所得的工具，比如 DW ，直接使用Html语言编写网页文件，
那应该不会是一种享受-_-#</p>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
</div>
<blockquote>
<p>可能有许多高手会讲： <em>我就是喜欢直接编辑Html代码，那绝对是一种享受！</em></p>
<p>是啊，可能那是一种享受，但是你享受的是编写代码，而不是设计页面。
Html并不是编程，代码不是决定因素，而外观设计才是重要的。所见即所得把开发者从代码中解救出来，
使它们把心思都用在设计上，这才是它的伟大之处！</p>
<p>同样的，Word之类的工具，也是一种所见即所得的工具。
不同的是，doc 文件的复杂程度要远远高于 Html，您不太可能直接编辑它。</p>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id54" id="id3" name="id3">所想即所得</a></h2>
<p>WYTIWYG ( What You Think Is What You Get )</p>
<blockquote>
<p>我们已经知道了，所见即所得偏重的是外观设计，而不是代码。看起来不错，不过这种模式也有一些缺点。</p>
<p>比如我想强调某事，我可能就会有点犹豫……我是应该用粗体呢？还是应该用红色的字体？
还有什么其它更好的方法么？</p>
<p>假如现在我使用的是白色的背景，我使用红色的字体来表示强调。
由于各种可能的原因，我需要把这些内容转移到另外一个地方，不巧的是，
那个页面的背景使用的颜色和红色比较接近，比如说粉红色吧，
如此一来，我的红色的文字反而没有正文的黑色文字醒目，本来是表示强调的，
反而成了忽视……</p>
<p>如果手动修改这些地方，可能会非常的麻烦，因为我可能用红色表示强调，用粗体表示感叹……
而这些内容可能会出现在许多不同的场合，这可怎么办啊？</p>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
</div>
<blockquote>
<p>这个问题很容易解决，答案就是 <strong>所想即所得</strong> ！例如：</p>
<pre class="literal-block">
这里是&lt;强调&gt;强调&lt;/强调&gt;，这里是&lt;感叹&gt;感叹&lt;/感叹&gt;
……
</pre>
<p>再使用一个样式定义，例如：</p>
<pre class="literal-block">
强调 = 红色字体
感叹 = 粗体
……
</pre>
<p>然后使用转换程序，根据预先定义的样式，自动将 <tt class="docutils literal"><span class="pre">&lt;强调&gt;</span></tt> 转换为 <tt class="docutils literal"><span class="pre">&lt;b&gt;</span></tt> ，
将 <tt class="docutils literal"><span class="pre">&lt;感叹&gt;</span></tt> 转换为 <tt class="docutils literal"><span class="pre">&lt;font</span> <span class="pre">color=red&gt;</span></tt> 就可以了。</p>
<p>如果我们想将强调改用绿色，只要将样式定义改一下：</p>
<pre class="literal-block">
强调 = 绿色字体
</pre>
<p>也可以方便的转换为其它文件，比如 <strong>pdf</strong> 或者其它格式──只要有相应的转换程序就可以了。</p>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
</div>
<blockquote>
<p>所见即所得工具不需要编写代码，将开发者从代码只解救出来，使其专注于设计；
而所想即所得工具不需要设计外观，把设计者从外观中解救出来，使其专注行思考！</p>
<p>事实上，这种使用标签的模式比较接近 <strong>DocBook</strong> ，当然了，标签不会是中文的。
从国际主义精神的角度，我们要照顾到外国友人──据说外国友人的中文普遍不太好：）</p>
<p>从通用性的角度来考虑，标签基本上使用英文；从减少输入的角度考虑，标签应该尽量简短
──很多标签使用缩写。</p>
<p>不过标签这种方式本身就很麻烦，特别是使用尖括号的标签。能不能再简单一些呢？</p>
</blockquote>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id55" id="id4" name="id4"><em>re</em><strong>Structured</strong><sup>Text</sup></a></h1>
<blockquote>
<p><em>re</em><strong>Structured</strong><sup>Text</sup> ，重构建文本，是一种优秀的写作工具，对于元素的定义已经不只是简化，而是进行了充分的优化。</p>
<p>上面我们提到了元素，我们把它理解为一个对象的基本组成部分。例如 <tt class="docutils literal"><span class="pre">&lt;b&gt;粗体&lt;/b&gt;</span></tt> 、
<tt class="docutils literal"><span class="pre">&lt;强调&gt;强调&lt;/强调&gt;</span></tt> 都是元素，只是组成的方式不同而已，一种是所见即所得，
另一种是所想即所得。</p>
<p><tt class="docutils literal"><span class="pre">&lt;bold&gt;</span></tt> 到 <tt class="docutils literal"><span class="pre">&lt;b&gt;</span></tt> 是一种简化，不过还是很麻烦。使用一些不常用而且又容易输入的符号，例如
<tt class="docutils literal"><span class="pre">**</span></tt> 就是优化了</p>
<p>在 <em>re</em><strong>Structured</strong><sup>Text</sup> 中，正是使用 <tt class="docutils literal"><span class="pre">**</span></tt> 来表示强调！</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="42%" />
<col width="58%" />
</colgroup>
<tbody valign="top">
<tr><td>原始内容</td>
<td>显示结果</td>
</tr>
<tr><td>*强调*</td>
<td><em>强调</em></td>
</tr>
<tr><td>**特别强调**</td>
<td><strong>特别强调</strong></td>
</tr>
<tr><td>``*原文引用*``</td>
<td><tt class="docutils literal"><span class="pre">*原文引用*</span></tt></td>
</tr>
<tr><td>\*原文*</td>
<td>*原文*</td>
</tr>
</tbody>
</table>
</blockquote>
</blockquote>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id56" id="id5" name="id5">基本元素</a></h1>
<blockquote>
<dl class="docutils">
<dt>这一部分内容十分重要，理解透彻后便能够无往而不利。</dt>
<dd>不然的话，在实际使用的过程中，
您可能会觉得 <em>re</em><strong>Structured</strong><sup>Text</sup> 比较莫名其妙，有点怪怪的……</dd>
</dl>
</blockquote>
<div class="section">
<h2><a class="toc-backref" href="#id57" id="id6" name="id6"><strong>字串元素</strong></a></h2>
<blockquote>
<p>连续的字符串构成的元素，为字串元素。 看下面的例子</p>
<pre class="literal-block">
**强调** 就是一个字串元素。普通文本也是一个字串元素。

    第三个字串元素
</pre>
<p><tt class="docutils literal"><span class="pre">**强调**</span></tt> 是第一个字串元素；它后面的文本，是第二个字串元素。</p>
<p>如果您够细心，您会发现，字串元素之间使用 <strong>空格</strong> 分隔。
在字串元素的级别， <strong>缩进</strong> 和 <strong>换行符</strong> 也能够分隔字串元素。</p>
<p>严格来说，字串元素 <strong>空格</strong> 和 <strong>.</strong> <strong>,</strong> <strong>?</strong> <strong>!</strong> 等英文标点结束</p>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id58" id="id7" name="id7"><strong>行元素</strong></a></h2>
<blockquote>
<p>下划线（有时包括上划线）和文本构成的元素，例如标题、表格</p>
<pre class="literal-block">
标题
====
</pre>
<p>表格：</p>
<pre class="literal-block">
=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======
</pre>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
</div>
<blockquote>
<p>行元素中，下划线使用符号构成，例如</p>
<pre class="literal-block">
Chapter 1 Title
===============

Section 1.1 Title
-----------------

Subsection 1.1.1 Title
~~~~~~~~~~~~~~~~~~~~~~
</pre>
<p>构成下划线的符号长度，应不小于文本长度。（一个汉字占两个字符）</p>
<blockquote>
<!-- 表格使用一条带有分隔符的上划线，多个行元素构成 -->
</blockquote>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id59" id="id8" name="id8"><strong>块元素</strong></a></h2>
<blockquote>
<p>具有相同缩进的元素为块元素，例如段落、表格</p>
<pre class="literal-block">
┊   第一行
┊   第二行
┊   第三行
┊
┊   第二段
</pre>
<dl class="docutils">
<dt>块元素使用一个 <strong>空行</strong> 结束，也就是一个 <strong>垂直分隔符</strong> 。上面的例子中包含了两个块元素。</dt>
<dd>连续出现多个空行时，作为一个空行处理。</dd>
<dt>可以使用 <em>Line Blocks</em> 增加空行，使单独一行中只有一个 <strong>|</strong> 符号即可</dt>
<dd>（前后都要有空行，因为它也是一个 块元素）</dd>
</dl>
<p>见 <a class="reference" href="#id11">行块元素</a></p>
</blockquote>
<p><strong>技巧：</strong> 只要没有空行，不管换多少次行，都会处理为一行。
建议您将每行的内容控制在50个汉字或者100个字母之内，
尽量在标点符号处手动换行，以增加源文件的可读性。</p>
<!-- 制表符 ─ │ └ ┌ ┘ ┐ ┆ ┊ ┄ ┈ ├ ┼ ┬ -->
<div class="line-block">
<div class="line"><br /></div>
</div>
<blockquote>
<p>块元素也允许逐行增加缩进，例如</p>
<pre class="literal-block">
┊   第一行
┊   第二行
┊     第三行
┊                        第四行
</pre>
<p>相同缩进的行处理为一行；不同缩进，无论缩进多少，都处理为一个缩进。上面文本实际显示为</p>
<pre class="literal-block">
┆    第一行第二行
┆        第三行
┆            第四行
</pre>
<p>段落的缩进由其首行缩进决定</p>
<p>事实上，这种形式属于 <a class="reference" href="#dylb"><strong>定义列表</strong></a></p>
<blockquote>
<!-- 左上角 -->
</blockquote>
</blockquote>
<p><strong>注意：</strong> <tt class="docutils literal"><span class="pre">字串元素</span></tt> 可以作为 <tt class="docutils literal"><span class="pre">行元素</span></tt> 的子集，它们都可以作为 <tt class="docutils literal"><span class="pre">块元素</span></tt> 的子集。</p>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id60" id="id9" name="id9">特殊元素</a></h1>
<blockquote>
<p>这部分内容稍微复杂，建议您动起手来，摸着石头过河。</p>
<p><a class="reference" href="#restructuredtext">搭建reStructuredText环境</a> 和 <a class="reference" href="#id36">reStructuredText命令</a> 部分内容，
您可以先参考一下：）</p>
<p>当然了，前面部分的内容，尽管看起来比较简单，
不过您还是可以实验一下，多少会有一些帮助的……</p>
</blockquote>
<div class="section">
<h2><a class="toc-backref" href="#id61" id="id10" name="id10">页面元素</a></h2>
<blockquote>
<p>类似行元素，但是不包含缩进，例如标题、分隔线</p>
<pre class="literal-block">
==============
文档标题
==============

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~  (分隔线)

章节标题
===========

二级章节标题
-----------

二级章节标题
-----------

章节标题
===========
</pre>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id62" id="id11" name="id11">行块元素</a></h2>
<blockquote>
<p>在某些情况下，一个段落中需要用逐行向外缩进，比如中文排版；</p>
<blockquote>
<div class="line-block">
<div class="line-block">
<div class="line">段落首行</div>
</div>
<div class="line">第二行向外缩进</div>
<div class="line">其它行和第二行相同</div>
</div>
</blockquote>
<p>或者手动换行而不分段，甚至是更加复杂的装饰性文字……</p>
<blockquote>
<div class="line-block">
<div class="line-block">
<div class="line-block">
<div class="line">&lt;&gt;</div>
</div>
<div class="line">&lt;    &gt;</div>
</div>
<div class="line">&lt;   &lt;&gt;   &gt;</div>
<div class="line-block">
<div class="line">&lt;    &gt;</div>
<div class="line-block">
<div class="line">&lt;&gt;</div>
</div>
</div>
</div>
</blockquote>
<p>而段落中只能逐行向内缩进；相同的缩进会自动合并为一行，不能手动换行</p>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
</div>
<blockquote>
<div class="line-block">
<div class="line">这些问题可以使用 <em>行块元素</em> 来解决。</div>
<div class="line">在每一行起始处添加引导符 <strong>|</strong> 和 <em>缩进</em></div>
</div>
<blockquote>
<pre class="literal-block">
|          段落首行
|       第二行向外缩进
|       其它行和第二行相同
</pre>
</blockquote>
<div class="line-block">
<div class="line">相邻的行块元素，它们的引导符缩进应相同。</div>
<div class="line">行块引导符后的一个空格为分隔符，是必须的！处理时忽略</div>
</div>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id63" id="id12" name="id12">超级块元素</a></h2>
<blockquote>
<p>类似块元素，但是可以包含空行，并且内部可以随意缩进。例如注释、块引用</p>
<p>包含有超级块引导符的行为引导行。
超级块起始时相对引导行向内缩进；
结束时使用一个空行，并且向外缩进等于或者超过引导行</p>
<pre class="literal-block">
外部块
  引导行 &lt;引导符&gt;

      向内缩进
    超级块内部可以自由缩进

    可以使用空行

  新的开始.这一行前需要空行，起码与引导行缩进相同，或者更外
</pre>
</blockquote>
<p><strong>注释</strong></p>
<blockquote>
<p>注释是以 <strong>..</strong> 起始的超级块元素，注释中的内容只在源文件中显示，
并不在结果中显示</p>
<pre class="literal-block">
.. 注释
 第二行
 第三行

  第二段
 第六行

新的开始
</pre>
<p>引导符 <tt class="docutils literal"><span class="pre">..</span></tt> 前不能有其它字符，之后要有一个空格与注释内容分隔开
（ <tt class="docutils literal"><span class="pre">..</span></tt> 同时是一个字串元素，前后都要有分隔符）</p>
</blockquote>
<p><strong>块引用</strong></p>
<blockquote>
<p>块引用是以 <strong>::</strong> 起始的超级块元素，块引用的内容不作任何处理，
以原文显示</p>
<pre class="literal-block">
块引用 ::

 第一行
  第二行

 第四行

新的开始
</pre>
<p>引导符 <tt class="docutils literal"><span class="pre">::</span></tt> 后必须有一个空行</p>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id64" id="id13" name="id13">物件元素</a></h2>
<blockquote>
<p>用来定义一个物件，物件元素由行内<tt class="docutils literal"><span class="pre">字串元素</span></tt>或注释中的<tt class="docutils literal"><span class="pre">块元素</span></tt>构成</p>
<p>以 <strong>_</strong> 结尾的字串元素，例如 <tt class="docutils literal"><span class="pre">链接_</span></tt> <tt class="docutils literal"><span class="pre">[脚注]</span></tt></p>
<p>以 <strong>|</strong> 包裹的字串元素，例如 <tt class="docutils literal"><span class="pre">|别名|</span></tt></p>
<p>它们都需要在注释中进行解释：</p>
<pre class="literal-block">
这里是一个 链接_ 。 [脚注]_

.. _链接: http://xxx

.. [脚注] xxxxxx


.. note:: 注意
</pre>
<p>一些具有特殊功能的物件，比如索引 <tt class="docutils literal"><span class="pre">contents::</span></tt> ，被直接写到注释中去</p>
<pre class="literal-block">
.. image:: 图片
.. contents:: 索引
</pre>
<p>参见 <a class="reference" href="#id34">预定义</a></p>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id65" id="id14" name="id14">自定义元素</a></h2>
<blockquote>
<p>例如文档信息，实际效果见页面顶部</p>
<pre class="literal-block">
:作者: Laurence
:邮箱: 2999am&#64;gmail.com
:ID:  Kardinal
:版权: This document has been placed in the public domain
:参考: 《Quick |rst| 》 《结构化文本入门(Karron Qiu)》

.. 技巧:: 自定义
</pre>
<p>使用以下格式</p>
<pre class="literal-block">
:&lt;名称&gt;:`字符串`

.. &lt;名称&gt;:: 字符串
</pre>
<p>在Html输出中添加</p>
<pre class="literal-block">
&lt;span class=&quot;&lt;名称&gt;&quot;&gt;字符串&lt;/span&gt;
</pre>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
</div>
<blockquote>
<em>re</em><strong>Structured</strong><sup>Text</sup> 系统内建了许多预定义对象，来完成特定功能。见 <a class="reference" href="#id34">预定义</a></blockquote>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id66" id="id15" name="id15">对象</a></h1>
<div class="section">
<h2><a class="toc-backref" href="#id67" id="id16" name="id16">标题</a></h2>
<blockquote>
<p><em>re</em><strong>Structured</strong><sup>Text</sup> 会根据下划线读取文档的标题，并且可以自动组织索引</p>
<pre class="literal-block">
=====================
文档标题
=====================

--------
子标题
--------

章节标题
========

...
</pre>
<p>具有同样带修饰线类型的标题，属于树状索引的同一层级</p>
<p>带有上划线的标题，和不带上划线的标题是不同类型。上面例子中，文档标题和章节标题就不属于同一层级</p>
<p>自上而下，越先出现的标题类型，层级越高</p>
<p>为了简单起见，我们只写标题的修饰线</p>
<pre class="literal-block">
===
---
---
^^^
^^^
^^^
---
---
^^^
</pre>
<p>我们可以看到，自上而下，最先出现的标题是 === ，所以它处于最高层级；然后是 --- ，所以它处于第二层；最后是 ^^^</p>
<p>如果画成树形图，就是这样的</p>
<pre class="literal-block">
===
│
├ ---
├ ---
│   ├ ^^^
│   ├ ^^^
│   └ ^^^
├ ---
├ ---
│   └ ^^^
</pre>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id68" id="id17" name="id17">行内</a></h2>
<p>多表示语气，如 <tt class="docutils literal"><span class="pre">**强调**</span></tt></p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="17%" />
<col width="16%" />
<col width="67%" />
</colgroup>
<tbody valign="top">
<tr><td>源文本</td>
<td>显示结果</td>
<td>说明</td>
</tr>
<tr><td>*强调*</td>
<td><em>强调</em></td>
<td>通常显示为斜体</td>
</tr>
<tr><td>**特别强调**</td>
<td><strong>特别强调</strong></td>
<td>通常显示为粗体</td>
</tr>
<tr><td>`字符串`</td>
<td><cite>字符串</cite></td>
<td>字符串内包含空格和标点符号时，处理为单个字串</td>
</tr>
<tr><td>``行内引用``</td>
<td><tt class="docutils literal"><span class="pre">行内引用</span></tt></td>
<td>显示为等宽字体，保留空格，不断行</td>
</tr>
<tr><td>简单链接_</td>
<td><a class="reference" href="#id21">简单链接</a></td>
<td>简单的链接名称 &lt;链接名称&gt;_</td>
</tr>
<tr><td>`词组 链接`_</td>
<td><a class="reference" href="#id22">词组 链接</a></td>
<td>带空格、标点的链接名称</td>
</tr>
<tr><td>无名链接__</td>
<td><a class="reference" href="http://forum.ubuntu.org.cn/">....Ubuntu.......</a></td>
<td>链接目标中不使用名称。适合大段文字的链接</td>
</tr>
<tr><td>_`链接目标`</td>
<td><span class="target" id="id18">链接目标</span></td>
<td>链接的实际指向 _&lt;链接名称&gt;:</td>
</tr>
<tr><td>|物件别名|</td>
<td><img alt="物件别名" src="http://forum.ubuntu.org.cn/templates/subSilver/images/folder_big.gif" /></td>
<td>用来给物件指定一个别名。文本、图片、链接及其它</td>
</tr>
<tr><td>脚注名称 [1]_</td>
<td><a class="footnote-reference" href="#id24" id="id19" name="id19">[1]</a></td>
<td>见脚注</td>
</tr>
<tr><td>引文名称 [引文]_</td>
<td><a class="citation-reference" href="#id25" id="id20" name="id20">[引文]</a></td>
<td>见引文</td>
</tr>
<tr><td>http://...</td>
<td><a class="reference" href="http://">http://</a>...</td>
<td>独立链接</td>
</tr>
</tbody>
</table>
<pre class="literal-block" id="id21">
.. _简单链接:
</pre>
<pre class="literal-block" id="id22">
.. _`词组 链接`:
</pre>
<pre class="literal-block">
__ http://forum.ubuntu.org.cn/    无名链接
</pre>
<pre class="literal-block">
..  |物件别名| image:: http://forum.ubuntu.org.cn
   /templates/subSilver/images
   /folder_big.gif
</pre>
<table class="docutils footnote" frame="void" id="id24" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id19" name="id24">[1]</a></td><td>脚注1</td></tr>
</tbody>
</table>
<pre class="literal-block">
.. [1] 脚注1
</pre>
<table class="docutils citation" frame="void" id="id25" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id20" name="id25">[引文]</a></td><td>内容</td></tr>
</tbody>
</table>
<pre class="literal-block">
.. [引文] 内容
</pre>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id69" id="id26" name="id26">脱字符</a></h2>
<blockquote>
<p><em>re</em><strong>Structured</strong><sup>Text</sup> 使用 <strong>\</strong> 作为脱字符，脱字符引导的字串元素不具有特殊涵义，以本来面目显示</p>
<table border="1" class="docutils">
<colgroup>
<col width="43%" />
<col width="57%" />
</colgroup>
<tbody valign="top">
<tr><td>**强调**</td>
<td><strong>强调</strong></td>
</tr>
<tr><td>\**强调**</td>
<td>**强调**</td>
</tr>
</tbody>
</table>
<p>输入 <strong>\</strong> 字符，可以使用 <strong>\\</strong></p>
</blockquote>
<div class="tip">
<p class="first admonition-title">Tip</p>
<p class="last">使用 脱字符+空格 (<tt class="docutils literal"><span class="pre">\_</span></tt>)作为分隔符，可以消除字串元素之间的空格</p>
</div>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id70" id="id27" name="id27">链接</a></h2>
<blockquote>
<p>链接主要包括以下几种</p>
<p><strong>独立链接</strong> ， <em>re</em><strong>Structured</strong><sup>Text</sup> 会自动将网址转换为链接。</p>
<p>例如 <a class="reference" href="http://www.ubuntu.org.cn/">http://www.ubuntu.org.cn/</a></p>
<pre class="literal-block">
http://www.ubuntu.org.cn/
</pre>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
</div>
<blockquote>
<p><strong>命名链接</strong> ，为链接命名，有助记忆和减少空间占用。</p>
<p>在正文中使用 <tt class="docutils literal"><span class="pre">&lt;链接名&gt;_</span></tt> ，注释中使用 <tt class="docutils literal"><span class="pre">_&lt;链接名&gt;:</span> <span class="pre">[链接目标]</span></tt></p>
<p>例如 <a class="reference" href="http://www.ubuntu.org.cn/">Ubuntu</a></p>
</blockquote>
<blockquote>
<pre class="literal-block">
Ubuntu_

.. _Ubuntu:  http://www.ubuntu.org.cn/
</pre>
<p>如果链接名中出现空格和标点符号，可以使用 <strong>`</strong> 将链接名包裹起来</p>
<pre class="literal-block">
`Ubuntu cn`_

.. _`Ubuntu cn`:  http://www.ubuntu.org.cn/
</pre>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
</div>
<blockquote>
<p><strong>无名链接</strong> ，不使用链接名的链接</p>
<p><a class="reference" href="http://www.ubuntu.org.cn/">主要用于将大段文字转换为链接。如果将这部分文字作为链接名，
链接名也将被写进注释中……</a></p>
</blockquote>
<blockquote>
<pre class="literal-block">
`主要用于将大段文字转换为链接。如果将这部分文字作为链接名，
链接名也将被写进注释中……`__

__ http://www.ubuntu.org.cn/
</pre>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
</div>
<blockquote>
<p>无名链接经常与命名链接一起使用</p>
<pre class="literal-block">
`这里是一大段文字………………`__

__ 一个命名链接_
</pre>
<p>可以在任意位置定义这个命名链接</p>
<pre class="literal-block">
.. _一个命名链接:
</pre>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
</div>
<blockquote>
<p><strong>锚点</strong> ，链接的目标地址留空，可以在当前位置标记锚点。</p>
<pre class="literal-block">
跳转到 锚点_

.. _锚点:

&lt;页面位置&gt;
</pre>
<p>点击锚点名称跳转到锚点标记处。</p>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
</div>
<blockquote>
<p><strong>标题链接</strong> ，跳转到文章内部的标题</p>
<p><em>re</em><strong>Structured</strong><sup>Text</sup> 定义标题的同时，还定义了一个标题链接，在正文中使用 <tt class="docutils literal"><span class="pre">标题名称_</span></tt> 可以跳转相应标题</p>
<pre class="literal-block">
标题名称
========

跳转到 标题名称_
</pre>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
</div>
<blockquote>
<p><strong>嵌入式链接</strong> ，链接目标嵌入到链接中。(<em>re</em><strong>Structured</strong><sup>Text</sup> 中没有通过，不建议使用)</p>
<p><tt class="docutils literal"><span class="pre">`Ubuntu</span> <span class="pre">&lt;http://www.ubuntu.org.cn&gt;`_</span></tt></p>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id71" id="id29" name="id29">物件别名</a></h2>
<blockquote>
<p>为一个物件元素定义一个别名</p>
<pre class="literal-block">
|H2O|

.. |H2O| replace:: H\ :sub:`2`\ O
</pre>
<p>输入 <tt class="docutils literal"><span class="pre">|别名|</span></tt> 便可以得到所定义的内容</p>
<p>上面例子中，输入 <tt class="docutils literal"><span class="pre">|H2O|</span></tt> ，得到 <tt class="docutils literal"><span class="pre">H\</span> <span class="pre">:sub:`2`\</span> <span class="pre">O</span></tt> ，也就是 H<sub>2</sub>O</p>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
</div>
<blockquote>
<p>可以定义别名的元素有 文本 链接 图像 Unicode字符 日期时间等</p>
<p>链接：</p>
<pre class="literal-block">
.. |别名| replace:: 字符串 （可以是独立链接）

.. _链接: 目标地址
.. |别名| replace:: 链接_
</pre>
<p>为链接创建别名时，使用命名链接，则别名替换为链接名称；
使用独立链接，则别名替换为目标地址。</p>
<p>为链接创建别名的时候，可以随意修改目标地址，但是链接名称要
使两处保持一致，不够方便；并且使用别名时一定要带链接，不够灵活</p>
<p>我们建议您使用 <em>别名链接</em> ，它能够方便的修改链接名称和目标地址，
并且可以灵活的输出各种格式</p>
<p id="bmlj"><strong>别名链接</strong> ，使用一个别名，定义链接名称和目标地址。</p>
<pre class="literal-block">
这是一个 |别名链接|_

.. |别名链接| replace:: 实际显示的链接名称

.. _别名链接: http://目标地址
</pre>
<p>实际相当于先定义一个别名，然后定义别名的链接。</p>
</blockquote>
<div class="note">
<p class="first admonition-title">Note</p>
<ul class="last simple">
<li><tt class="docutils literal"><span class="pre">|别名链接|</span></tt>      输出<em>replace</em>定义的字符串</li>
<li><tt class="docutils literal"><span class="pre">别名链接_</span></tt>       输出使用别名作为链接名称的链接</li>
<li><tt class="docutils literal"><span class="pre">|别名链接|_</span></tt>     输出链接名称定义的链接</li>
</ul>
</div>
<div class="line-block">
<div class="line"><br /></div>
</div>
<blockquote>
<p>图片：</p>
<pre class="literal-block">
.. |图片名称| image:: 图片路径
   :width: 宽度
   :height: 高度
   :target: 目标链接
</pre>
<p>Unicode字符：</p>
<pre class="literal-block">
.. |别名| unicode:: U+211
.. |200E| unicode:: 200 U+20AC
</pre>
<p>时间日期：</p>
<pre class="literal-block">
.. |当前时间| date:: %H:%M
</pre>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id72" id="id30" name="id30">列表</a></h2>
<blockquote>
<p>列表中，相同的层级使用相同的缩进。
列表中的所有条目都是块元素，要使用空行分隔</p>
<p>列表中同一层级不需要空行分隔。不同层级起始处必须有空行</p>
<pre class="literal-block">
列表：
  - 条目
  - 条目

      - 条目
      - 条目
  - 条目
</pre>
<ul class="simple">
<li>如果不包含复杂的层级，只要使用缩进开始列表，并且不需要空行</li>
<li>如果层级复杂，那么最好所有条目都以空行分隔，避免发生混乱</li>
</ul>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
<div class="line"><br /></div>
</div>
<blockquote>
<p><strong>要点列表</strong> 以 <strong>-</strong> <strong>+</strong> <strong>**</strong> 和一个空格作引导符，条目不计数</p>
<ul>
<li><p class="first">第一条</p>
<ul>
<li><p class="first">子条目一</p>
<blockquote>
<ul class="simple">
<li>第三级</li>
<li>第三级</li>
</ul>
</blockquote>
</li>
<li><p class="first">子条目二</p>
</li>
</ul>
</li>
<li><p class="first">第二条
还是第一行</p>
<p>第二条第二行</p>
<ul class="simple">
<li>子条目</li>
</ul>
</li>
<li><p class="first">第三条</p>
</li>
</ul>
<p>代码如下 ：</p>
<pre class="literal-block">
- 第一条

  - 子条目一

     - 第三级

     - 第三级

  - 子条目二

- 第二条
  还是第一行

  第二条第二行

  - 子条目

- 第三条
</pre>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
<div class="line"><br /></div>
<div class="line"><br /></div>
</div>
<blockquote>
<p><strong>枚举列表</strong> 使用一个数字或者字符，后跟 <strong>.</strong> <strong>)</strong> 或者使用 <strong>()</strong> 括起来，加一个空格</p>
<pre class="literal-block">
1. 数字

A. 大写字符

a. 小写字符

    3. 用不同数字开始的子列表

    4. 确认数字有正确的序号！

I.大写的罗马字符

i.小写的罗马字符

(1) 再来一个数字

1) 再来
</pre>
<p>可以使用 <strong>#</strong> 代替数字， <em>re</em><strong>Structured</strong><sup>Text</sup> 会自动排序</p>
<pre class="literal-block">
#) 一

#) 二

#) 三
</pre>
<ol class="arabic simple">
<li>一</li>
<li>二</li>
<li>三</li>
</ol>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
<div class="line"><br /></div>
<div class="line"><br /></div>
</div>
<blockquote id="dylb">
<p><strong>定义列表</strong> 为列表中的条目定义一个名称</p>
<pre class="literal-block">
要点列表
  只列出要点，条目不记数

定义列表
  为列表中的条目定义一个名称

枚举列表
  条目进行计数
</pre>
<dl class="docutils">
<dt>要点列表</dt>
<dd>只列出要点，条目不记数</dd>
<dt>定义列表</dt>
<dd>为列表中的条目定义一个名称</dd>
<dt>枚举列表</dt>
<dd>条目进行计数</dd>
</dl>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
<div class="line"><br /></div>
<div class="line"><br /></div>
</div>
<blockquote>
<p><strong>区块列表</strong> ，常用作联系薄</p>
<pre class="literal-block">
:作者: Laurence
:邮箱: 2999am&#64;gmail.com
:ID:  Kardinal &#64; Ubuntu.org.cn论坛
:版权: This document has been placed in the public domain
:参考: 《结构化文本入门(Karron Qiu)》
      《Quick |rst|\ 》
      《Vim |rst|\ 》
      《\ |rst| Interpreted Text Roles》
</pre>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">作者:</th><td class="field-body">Laurence</td>
</tr>
<tr class="field"><th class="field-name">邮箱:</th><td class="field-body"><a class="reference" href="mailto:2999am&#64;gmail.com">2999am&#64;gmail.com</a></td>
</tr>
<tr class="field"><th class="field-name">ID:</th><td class="field-body">Kardinal &#64; Ubuntu.org.cn论坛</td>
</tr>
<tr class="field"><th class="field-name">版权:</th><td class="field-body">This document has been placed in the public domain</td>
</tr>
<tr class="field"><th class="field-name">参考:</th><td class="field-body">《结构化文本入门(Karron Qiu)》
《Quick <em>re</em><strong>Structured</strong><sup>Text</sup>》
《Vim <em>re</em><strong>Structured</strong><sup>Text</sup>》
《<em>re</em><strong>Structured</strong><sup>Text</sup> Interpreted Text Roles》</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id73" id="id31" name="id31">表格</a></h2>
<blockquote>
<p>表格使用一条带有分隔符的上划线，和最少一条下划线构成</p>
<pre class="literal-block">
========   ==========
表格        表格
========   ==========
</pre>
<p>上划线下面为多行缩进相同的 <a class="reference" href="#id7">行元素</a> ，行元素的下划线应不短于行字符。</p>
<p>表格同一列的下划线，长度应相等。</p>
<p>上划线（顶部）的分隔符是必须的，它决定了表格可以拥有的列数，但是不影响相邻列的合并。</p>
<p>合并相邻的列，只要取消下划线的分隔符就可以了。</p>
<p>底部的下划线，应和上划线使用同样符号</p>
<pre class="literal-block">
===== ===== ===== ===== =====   以空格作分隔符，间距均匀。决定了这个表格最多可以有5列
11    12    13    14    15
----------- -----------------   下划线的长度应不小于字符长度
21    22    23    24    25
----- ----- ----- ----- -----   每一行的下划线，决定了相信列是否合并
31    32    33    34    35
----- ----------- -----------   如果不打算合并列，可以取消表内分隔线
41    42    42    44    45
=============================   底线必须与上划线使用相同符号
</pre>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="20%" />
<col width="20%" />
<col width="20%" />
<col width="20%" />
</colgroup>
<tbody valign="top">
<tr><td colspan="2">11    12</td>
<td colspan="3">13    14    15</td>
</tr>
<tr><td>21</td>
<td>22</td>
<td>23</td>
<td>24</td>
<td>25</td>
</tr>
<tr><td>31</td>
<td colspan="2">32    33</td>
<td colspan="2">34    35</td>
</tr>
<tr><td colspan="5">41    42    42    44    45</td>
</tr>
</tbody>
</table>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
</div>
<blockquote>
<p>如果想制作更复杂的表格，例如合并相邻行，则需要使用列分隔线</p>
<pre class="literal-block">
+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| body row 1 | column 2   | column 3  |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may  | - Cells   |
+------------+ span rows. | - contain |
| body row 4 |            | - blocks. |
+------------+------------+-----------+
</pre>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
<div class="line"><br /></div>
</div>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id74" id="id32" name="id32">脚注</a></h2>
<blockquote>
<p>脚注使用方括号包裹起来</p>
<pre class="literal-block">
这里是一个脚注 [1]_

.. [1] 这里是脚注的内容
</pre>
<p>行内脚注后面也有一个 <strong>_</strong> 符号，它是当作一个链接处理的。</p>
<p>脚注的名称可以使用 数字 <strong>#</strong> 和 <strong>*</strong> ，使用数字时需要手机排列</p>
<p>推荐使用 <tt class="docutils literal"><span class="pre">#</span></tt> 作为脚注名称， <em>re</em><strong>Structured</strong><sup>Text</sup> 会自动计数。
使用 <tt class="docutils literal"><span class="pre">*</span></tt> 作为脚注名称， <em>re</em><strong>Structured</strong><sup>Text</sup> 会把它们替换成一些花哨的符号</p>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id75" id="id33" name="id33">提示符引用</a></h2>
<blockquote>
<p>使用 <strong>&gt;&gt;&gt;</strong> 作为引导符，模仿交互式命令提示行</p>
<pre class="doctest-block">
&gt;&gt;&gt; rst2html -r 4 --stylesheet-path=/home/user/html4css1.css rst html
</pre>
<p>引用块不能空行</p>
<p>原文本</p>
<blockquote>
<div class="line-block">
<div class="line">&gt;&gt;&gt; rst2html -r 4 --stylesheet-path=/home/user/html4css1.css rst html</div>
</div>
</blockquote>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id76" id="id34" name="id34">预定义</a></h2>
<blockquote>
<p><em>re</em><strong>Structured</strong><sup>Text</sup> 中内建了许多字串元素作为功能对象</p>
<p>标准。行内使用：</p>
<pre class="literal-block">
:emphasis:
*强调*
:emphasis:`强调`

:literal:
``原文``
:literal:`原文`

:strong:
**特别强调**
:strong:`特别强调`

:subscript:`下标`
:sub:`下标`

:superscript:`上标`
:sup:`上标`

:title-reference:`标题`
:title:`标题`
:t:`标题`
</pre>
<p>特殊。注释中使用：</p>
<pre class="literal-block">
.. contents:: 索引
   :depth: 3  标题搜索深度

.. image :: (路径)/image.png
    :target: http://ubuntu.org.cn

.. figures :: 形状/figures.png


.. sidebar:: 侧边栏标题
   :subtitle: 子标题

     These lines are sidebar content interpreted
     as body elements.

.. rubric:: 醒目提示（内容）

.. topic:: 话题


.. tip:: tip内容

.. note:: note内容

.. warning:: warning内容

.. important::

.. attention::

.. danger::

.. error::

.. caution::
</pre>
</blockquote>
<div class="line-block">
<div class="line"><br /></div>
<div class="line"><br /></div>
</div>
<blockquote>
<p>字串元素间使用脱字符和空格作为分隔符，可以不显示空格，例如:</p>
<blockquote>
H<sub>2</sub>O</blockquote>
<pre class="literal-block">
H\ :sub:`2`\ O
</pre>
</blockquote>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id77" id="id35" name="id35">项目管理</a></h1>
<blockquote>
<p>编写一个较大规模的文档时，使用单一源文件，编辑起来可能十分吃力。</p>
<p><em>re</em><strong>Structured</strong><sup>Text</sup> 允许使用一个文件，在转换时将其它文件的内容读取进来，
以便更好的管理文档项目</p>
<div class="line-block">
<div class="line">.. header:: 源文件路径，读取到文件头部</div>
<div class="line">.. include:: 源文件路径，按顺序读取</div>
<div class="line">.. footer:: 源文件路径，读取到文件尾部</div>
</div>
<p>例如：</p>
<pre class="literal-block">
.. header:: dir/header.rst
.. include:: dir/1.rst
.. include:: dir/2.rst
.. include:: dir/3.rst
.. footer:: footer.rst
</pre>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">不能够递归读取</p>
</div>
</blockquote>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id78" id="restructuredtext" name="restructuredtext">搭建reStructuredText环境</a></h1>
<div class="section">
<h2><a class="toc-backref" href="#id79" id="linux" name="linux">Linux</a></h2>
<blockquote>
<p><strong>Ubuntu</strong> 或者 <strong>Debian</strong> 系统中，使用APT安装</p>
<pre class="doctest-block">
&gt;&gt;&gt; sudo apt-get install python-docutils
</pre>
<p><tt class="docutils literal"><span class="pre">/usr/share/python-docutils/</span></tt> 目录中包含了相关的工具，
我们经常要用到的工具是 <tt class="docutils literal"><span class="pre">rst2html.py</span></tt> 。</p>
<p>在安装好之后，系统通常自动为它建立了链接，直接运行 <strong>rst2html</strong> 命令即可。</p>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id80" id="windows" name="windows">Windows</a></h2>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id81" id="id36" name="id36">reStructuredText命令</a></h1>
<blockquote>
<dl class="docutils">
<dt><strong>rst2html [参数] &lt;源文件.rst&gt; [目标文件.html]</strong></dt>
<dd><div class="first last line-block">
<div class="line">如果不指定目标文件，而输出Html代码，并不生成文件</div>
<div class="line">-r &lt;levle&gt; 设定报告级别，默认为 <strong>2</strong></div>
<div class="line">--tab-width=&lt;width&gt; 设定输出的缩进宽度，默认<strong>8</strong>个空格</div>
<div class="line">--stylesheet-path=&lt;file&gt; 指定CSS文件</div>
<div class="line">--embed-stylesheet 使用嵌入式CSS</div>
<div class="line">--footnote-references=&lt;format&gt; 脚注格式。 <strong>barckets</strong>方括号 <strong>superscript</strong>上标</div>
<div class="line">--compact-lists 忽略列表中多余的空行，默认 <strong>enabled</strong></div>
<div class="line">--config=&lt;file&gt;  指定配置文件</div>
<div class="line">--footnote-backlinks 允许从脚注跳回原文，默认选项</div>
<div class="line">--toc-top-backlinks 允许从标题跳回索引，默认选项</div>
</div>
</dd>
</dl>
</blockquote>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id82" id="id37" name="id37">定制</a></h1>
<blockquote>
<p><strong>/usr/share/python-docutils/docutils.conf</strong> 为配置文件</p>
<pre class="literal-block">
# These entries affect all processing:
[general]
source-link: yes
datestamp: %Y-%m-%d %H:%M UTC
generator: on

# These entries affect HTML output:
[html4css1 writer]
# Required for docutils-update, the website build system:
stylesheet-path: ../docutils/writers/html4css1/html4css1.css
embed-stylesheet: no
field-name-limit: 20
</pre>
</blockquote>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id83" id="id38" name="id38">代码风格</a></h1>
<div class="section">
<h2><a class="toc-backref" href="#id84" id="id39" name="id39">缩进</a></h2>
<blockquote>
<p>尽量使用固定长度的空格作为缩进，推荐您使用 <strong>4</strong> 个空格作为一个缩进</p>
<p>虽然在理论上，缩进可以使用任意长度，但是那样容易引起混乱，例如：</p>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id85" id="id40" name="id40">空行</a></h2>
<blockquote>
<p>有些情况下，空行并不是必须的，比如标题和之后的内容。</p>
<p>不过我们建议您还是尽量使用空行，以免不必要的麻烦。</p>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id86" id="id41" name="id41">下划线</a></h2>
<blockquote>
理论上，下划线只要和文字的长度相同就可以了，
不过我们建议主您使用比较长，且长度固定的下划线 例如 <strong>50</strong></blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id87" id="id42" name="id42">标题</a></h2>
<blockquote>
<p>下划线使用的符号比较重要。</p>
<p>如果能够养成一个固定的习惯，在处理较大规模的文档时，可以避免许多麻烦</p>
<p>推荐以下几套</p>
<table border="1" class="docutils">
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<tbody valign="top">
<tr><td>#####</td>
<td>=====</td>
<td>^^^^^</td>
</tr>
<tr><td>+++++</td>
<td>-----</td>
<td>&gt;&gt;&gt;&gt;&gt;</td>
</tr>
<tr><td>*****</td>
<td>~~~~~</td>
<td>&lt;&lt;&lt;&lt;&lt;</td>
</tr>
</tbody>
</table>
<p>建议您使用带上划线的第一级符号作为文章标题</p>
<p>全部可选符号包括</p>
<pre class="literal-block">
= - ` : ' &quot; ~ ^ _ * + # &lt; &gt;
</pre>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id88" id="id43" name="id43">标题链接</a></h2>
<blockquote>
<p>请尽量避免重复的标题，特别是存在大量标题链接的情况下。</p>
<p>如果同时存在多个名称相同的标题，并且有指向该名称的标题链接，
<em>re</em><strong>Structured</strong><sup>Text</sup> 无法确定哪一个标题是真正的目标，这时就会发生错误。</p>
<p>而使用标题链接链接越多，发生这种错误的几率越大~</p>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id89" id="id44" name="id44">表格</a></h2>
<blockquote>
<p>表格尽量使用空格作分隔符</p>
<p>如果没有特殊要求，表格包含上划线和底线就可以了，例如：</p>
<pre class="literal-block">
=======  =======
aaaaaa   111111
bbbbb    2222222
cccc     3
=======  =======
</pre>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id90" id="id45" name="id45">别名</a></h2>
<blockquote>
建议将别名定义放在页面顶部，便于维护</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id91" id="id46" name="id46">链接</a></h2>
<blockquote>
<p>请尽量使用独立链接、无名链接、标题链接和<a class="reference" href="#bmlj"><strong>别名链接</strong></a></p>
<p>定义别名链接的两行注释中间不要空行，便于阅读</p>
<pre class="literal-block">
.. |bmlj| replace:: **别名链接**
.. _bmlj:

**别名链接**
</pre>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id92" id="id47" name="id47">列表</a></h2>
<blockquote>
如无必要，请尽量使用要点列表和定义列表。枚举列表更适合作为章节</blockquote>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id93" id="id48" name="id48">编辑器设定</a></h1>
<div class="section">
<h2><a class="toc-backref" href="#id94" id="vim" name="vim">Vim</a></h2>
<blockquote>
下载 <a class="reference" href="http://www.google.com">vst.vim</a> 文件，拷贝到Vim的插件目录即可。</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id95" id="emacs" name="emacs">Emacs</a></h2>
<blockquote>
安装 <a class="reference" href="http://www.google.com">rst.el</a> 插件</blockquote>
<blockquote>
<p>将如下内容添加到 <tt class="docutils literal"><span class="pre">~/.emacs</span></tt> 文件中</p>
<pre class="literal-block">
;;RST
(require 'rst)
(add-hook 'text-mode-hook 'rst-text-mode-bindings)

(setq auto-mode-alist
(append '((&quot;\\.rst$&quot; . rst-mode)
(&quot;\\.rest$&quot; . rst-mode)) auto-mode-alist))
</pre>
</blockquote>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id96" id="faq" name="faq">FAQ</a></h1>
<div class="section">
<h2><a class="toc-backref" href="#id97" id="id49" name="id49">空行</a></h2>
<p>可以使用 <em>Line Blocks</em> 增加空行，使单独一行中只有一个 <strong>|</strong> 符号即可
（前后都要有空行，因为它也是一个 块元素）</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id98" id="id50" name="id50">消除空格</a></h2>
<p>使用 <tt class="docutils literal"><span class="pre">\_</span></tt> (脱字符和空格)代替空格作为分隔符，可以消除空格。</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id99" id="id51" name="id51">缩进和空格</a></h2>
<p>它们是等效的，如果不怕麻烦，您大可以完全使用空格，而不使用缩进</p>
</div>
</div>
</div>
<script type="text/javascript"><!--
var fhp_c_pc = navigator.userAgent.toLowerCase();
var fhp_ie = ((fhp_c_pc.indexOf("msie") != -1) && (fhp_c_pc.indexOf("opera") == -1));
var fhp_cs, fhp_wt, fhp_dm;

if (fhp_ie) {
        fhp_cs = document.charset;
}else{
        fhp_cs = document.characterSet;
}
fhp_dm = document.location;

fhp_wt = "";
fhp_wt = '<' + 'script src="http://web.fc2.com/header.php?cs=' + fhp_cs + '&dm=' + fhp_dm + '" charset="UTF-8"><' + '/script>';
fhp_wt += '<' + 'script src="http://web.fc2.com/footer/footer.php?cs=' + fhp_cs + '&dm=' + fhp_dm + '"><' + '/script>';
document.write(fhp_wt);
//--></script>
<!-- FC2, inc.-->
<img src="http://media.fc2.com/counter_img.php?id=50" style="visibility:hidden" alt="inserted by FC2 system" width="0" height="0">
<!-- FC2, inc.-->
</body>
</html>
